OLA 文档中心

主题

2026-07-20

获取鼠标图标 - GetCursorImage ​

函数简介 ​

获取鼠标图标，并输出光标热点（hotspot）与特征码字符串。特征码与本次返回的图像同源，适合作为缓存键，避免单独调用 GetCursorShape 时图码不一致。

接口名称 ​

GetCursorImage

DLL调用 ​

int64_t GetCursorImage(int64_t instance, int32_t* outXHotspot, int32_t* outYHotspot, int64_t* outShape);

参数说明 ​

参数名类型说明
ola长整数型OLAPlug对象的指针，由 CreateCOLAPlugInterFace 接口生成。
outXHotspot整数型指针输出参数：光标热点 X（相对图标左上角，对应 ICONINFO.xHotspot）。可为 NULL。
outYHotspot整数型指针输出参数：光标热点 Y（相对图标左上角，对应 ICONINFO.yHotspot）。可为 NULL。
outShape长整数型指针输出参数：光标特征码字符串指针（与本次图像同源，格式同 GetCursorShape）。可为 NULL。需调用 FreeStringPtr 释放。

示例 ​

SDK 调用 ​

cpp
#include "OLAPlugServer.h"

OLAPlugServer ola;
int32_t hotspotX = 0;
int32_t hotspotY = 0;
int64_t shapePtr = 0;
long handle = ola.GetCursorImage(&hotspotX, &hotspotY, &shapePtr);
// shapePtr 为特征码字符串，用完后 FreeStringPtr(shapePtr)
csharp
using OLAPlug;

var ola = new OLAPlugServer();
long handle = ola.GetCursorImage(out int hotspotX, out int hotspotY, out string shape);
// shape 已自动 FreeStringPtr；缓存键直接用 shape
python
from OLAPlugServer import OLAPlugServer

ola = OLAPlugServer()
handle, hotspotX, hotspotY, shape = ola.GetCursorImage()
# shape 已自动 FreeStringPtr；缓存键直接用 shape
java
import com.olaplug.OLAPlugServer;
import com.sun.jna.ptr.IntByReference;
import com.sun.jna.ptr.LongByReference;

OLAPlugServer ola = new OLAPlugServer();
IntByReference hotspotX = new IntByReference();
IntByReference hotspotY = new IntByReference();
LongByReference shapePtr = new LongByReference();
long handle = ola.GetCursorImage(hotspotX, hotspotY, shapePtr);
// shapePtr 需 FreeStringPtr
go
import "github.com/ola/olaplug/olaplug"

ola, _ := olaplug.NewOLAPlugServer("OLAPlug_x64.dll")
defer ola.ReleaseObj()
handle, hotspotX, hotspotY, shape := ola.GetCursorImage()
rust
use olaplug::OLAPlugServer;

let ola = OLAPlugServer::new("OLAPlug_x64.dll").unwrap();
let (handle, hotspot_x, hotspot_y, shape) = ola.get_cursor_image();
cpp
var ola = com("OlaPlug.OlaSoft")
var hotspotX = 0
var hotspotY = 0
var shape = ""
var handle = ola.GetCursorImage(hotspotX, hotspotY, shape)
vbscript
Set ola = CreateObject("OlaPlug.OlaSoft")
Dim hotspotX, hotspotY, shape
handle = ola.GetCursorImage(hotspotX, hotspotY, shape)
text
.局部变量 ola, OLAPlug
.局部变量 hotspotX, 整数型
.局部变量 hotspotY, 整数型
.局部变量 shape, 文本型
ola.创建 ()
handle ＝ ola.GetCursorImage (hotspotX, hotspotY, shape)
aardio
import OLAPlugServer;
var ola = OLAPlugServer();
var hotspotX, hotspotY, shape;
var handle = ola.GetCursorImage(hotspotX, hotspotY, shape);
text
变量 ola <类型 = OLAPlugServer>
变量 hotspotX <类型 = 整数>
变量 hotspotY <类型 = 整数>
变量 shape <类型 = 文本>
ola = 新建 OLAPlugServer
长整数 handle = ola.GetCursorImage (hotspotX, hotspotY, shape)
cpp
#include "OLAPlugServer.h"

OLAPlugServer ola;
int32_t hotspotX = 0;
int32_t hotspotY = 0;
int64_t shapePtr = 0;
long handle = ola.GetCursorImage(&hotspotX, &hotspotY, &shapePtr);

原生 DLL 调用 ​

cpp
long instance = CreateCOLAPlugInterFace();
int32_t hotspotX = 0;
int32_t hotspotY = 0;
int64_t shapePtr = 0;
long ptr = GetCursorImage(instance, &hotspotX, &hotspotY, &shapePtr);
if (shapePtr != 0) {
    // 读取特征码字符串后释放
    FreeStringPtr(shapePtr);
}
if (ptr != 0) {
    FreeImagePtr(instance, ptr);
}
csharp
using System.Runtime.InteropServices;

[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern long CreateCOLAPlugInterFace();
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern int FreeImagePtr(long ola, long ptr);
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern int FreeStringPtr(long ptr);
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern long GetCursorImage(long ola, out int outXHotspot, out int outYHotspot, out long outShape);

long instance = CreateCOLAPlugInterFace();
long ptr = GetCursorImage(instance, out int hotspotX, out int hotspotY, out long shapePtr);
// shapePtr 为 OLA_STRING_RETURN，用完后 FreeStringPtr(shapePtr)
if (shapePtr != 0) FreeStringPtr(shapePtr);
if (ptr != 0) FreeImagePtr(instance, ptr);
python
from ctypes import CDLL, c_int, c_int64, POINTER, byref

ola = CDLL("OLAPlug_x64.dll")
ola.CreateCOLAPlugInterFace.restype = c_int64
ola.GetCursorImage.argtypes = [c_int64, POINTER(c_int), POINTER(c_int), POINTER(c_int64)]
ola.GetCursorImage.restype = c_int64
instance = ola.CreateCOLAPlugInterFace()
hotspot_x = c_int(0)
hotspot_y = c_int(0)
shape_ptr = c_int64(0)
ptr = ola.GetCursorImage(instance, byref(hotspot_x), byref(hotspot_y), byref(shape_ptr))
if shape_ptr.value:
    ola.FreeStringPtr(shape_ptr.value)
if ptr:
    ola.FreeImagePtr(instance, ptr)

返回值 ​

返回值说明
（返回值）长整数型：OLAImage对象的地址。返回 0 表示失败。
outXHotspot整数型：光标热点 X（相对图标左上角）。失败时为 0。
outYHotspot整数型：光标热点 Y（相对图标左上角）。失败时为 0。
outShapeOLA_STRING_RETURN：与本次图像同源的特征码字符串指针。失败时为空串指针。需 FreeStringPtr。

注意事项 ​

项目说明
释放图片图片使用完后需要调用 FreeImagePtr 接口进行释放。
释放特征码outShape 为 OLA_STRING_RETURN，使用完后必须调用 FreeStringPtr。
缓存请用本次返回的 outShape 作为缓存键。不要先 GetCursorShape 再另一次 GetCursorImage，中间光标可能已变，导致特征码与图片对不上。
热点校正叠加绘制时请使用：drawX = mouseX - outXHotspot，drawY = mouseY - outYHotspot。若对显示尺寸做了缩放，热点也需按相同比例缩放后再减。
后台光标后台 DX 键鼠需在 mouse 中包含 cursor（如 dx.mouse.cursor）后，才从注入侧读取光标位图、热点与特征码。
可空输出outXHotspot / outYHotspot / outShape 传 NULL 时仍可正常返回图标句柄，仅不回写对应字段。